PRODUCT NAME

        The Amiga Guru Book
         by Ralph Babel

BRIEF DESCRIPTION

        This is an AmigaDOS reference manual that documents the Amiga
operating system with many examples in both C and assembler, and with
texts about the functions in AmigaDOS. The main text of this excellent
book gives specific and accurate descriptions of operating system
calls, library functions, devices, handlers, and information on the
filing systems. There is information on low-level hardware and
software, including memory maps of both, and covers OS1.2 up to 2.1.
This book is written in English.


ABOUT THE AUTHOR

        Babel really gets around. I've seen his name in several
programs I use. If you frequent the Amiga newsgroups on UseNet, you
will likely find Ralph in comp.sys.amiga.programmer. Amongst his
credits, he wrote all of Great Valley Products' Series-II drivers and
related system software.


COMPANY INFORMATION

        Author:         Ralph Babel
        ISBN:           No ISBN number
        Guru-No.:       8703 8001  C7E4 D9E4 (on the front cover)
        Guru Type:      AT_DeadEnd AG_OpenLib AO_ExecLib



HARDWARE AND SOFTWARE REQUIREMENTS

        None required, but an Amiga computer with a C compiler and an
        assembler highly recommended. AmigaDOS 2.04 also recommended.

MACHINES USED FOR TESTING

        Amiga 500 1 meg. chip ram, 8 meg. fast ram, OS1.3 and 2.1
        Amiga 4000/040 2 meg. chip ram, 14 meg. fast ram, OS3.0

SOFTWARE USED FOR TESTING

        SAS/C 6.3 Amiga C compiler and assembler development system.
        HiSoft DevPac 3.04 Amiga Assembler development system.

THE BOOK

        736 pages including index, and ASCII table on the last page.
        Paperback, well bound with coated covers.
        Text is well written, fluid and easy to read.
        Weight, about 2 pounds.


OVERVIEW


        This book is THE ultimate reference on AmigaDOS and will serve
any programmer very well, from novice to expert. If you are an Amiga
enthusiast interested in programming, then this is an essential book
to have on hand. Much of the information in this volume cannot be
found anywhere else, at least not all in one place.


REVIEW


        The Amiga Guru Book examples assume at least kickstart 37.175
(2.04), for the most part, although all examples will work with 1.3.
Some of the code fragments require 2.04 or later. They were developed
with SAS/C 5.10b/6.2 and the 2.04 include files. They also compile
with SAS/C 6.3 and the assembler examples assemble well with DevPac
V3.04 with a few minor changes.

        Throughout the text, obsolete features as well as 2.0 specific
features are clearly marked.

        The first chapters deal with datatypes of the C compilers, SAS
and Manx and datatypes of the Amiga operating system. There is
information on general programming guidelines, such as how to properly
access public data structures, determining stack size, with a C
example of how to switch to a bigger stack. Among the programming
guidelines, Babel points out many caveats, which some programmers
ignore, such as OpenLibrary(). "Library base pointers for any of the
IEEE math libraries must not be shared between different tasks!"

        There is a discussion on when to use Forbid()/Permit() and
Disable()/Enable(). Many system calls do a Forbid()/Permit() pair
already and these are cross referenced thoroughly, as are many other
functions that a programmer would use daily. I have seen much source
code that calls Forbid()/Permit(), then calls a function that already
does a Forbid()/Permit() pair.

        Data caching, copyback, and DMA are mentioned. Self modifying
code and how to implement it are explained, and many good reasons why
you normally should not make use of it.

        Chapter 3 is about Assembly language programming, how to call
system functions, about FD files and their structure, libraries and
their structure, macros and header files.

        Chapter 4 discusses C programming, in depth startup code and
compiler libraries.

        Chapters 5-8 are explicitly about SAS/C and what ANSI C is
about. It discusses the internals of the compiler, preprocessor
symbols, generated symbol references, and memory models such as small
code, small data, large code, and large data.. The examples given are
the familiar "Hello World", one with no startup code and the other
with startup code but in ANSI C with buffered I/O and memory
management. Also mentioned are the keywords __near, __far, and __huge
for coding of base relative code, and absolute code.

        Chapter 9 has a very good hardware memory map and details the
A500, A500+, A600, A2000, A3000, and of course the older A1000. It is
specific about where instruction accesses are allowed, data accesses,
what is actual RAM and shows proper caching for the ZorroII and
ZorroIII boards.

There is a short discussion about the Kickstart rom and sample source
on how to properly get the version of Kickstart and Workbench. The
famous startup diagnostics are explained; the colors at startup, both
OS1.3 and OS2.x. This also describes the keyboard diagnostics, the
blinking caps lock key, and what the blinks mean.

        Chapter 11 reveals everything you ever wanted to know about
Alerts, Gurus, and Traps. Alert numbers and Alert types are detailed,
how and why they happen.

        Chapter 12 to the end of the volume details the inner workings
of the disk operating system (DOS). The kernel, dos.library, Command
Line Interface, console handling, and the filesystem are extensively
discussed.
        The console handler, CON:, RAW:, and NEWCON: come first in
this section. Control and escape codes, as well as keycodes are
disclosed. There is C source to opening a CLI window on an Intuition
CUSTOMSCREEN, along with a little bit of BCPL "magic", which is
required prior to Kickstart 2.0.
        Next is the CLI itself and the AmigaShell. The special
characters for input/output redirection are revealed. These include
the "<" ">", the "< >"(under DOS2.0), and ">>" for standard output
append mode only. Babel points out that the "H" bit under DOS2.0
originally meant "hidden", but Shell 2.0 uses the "H" bit to hold pure
executables in the DOS resident list.
        Complete source code to a user shell is in this section and it
is well documented. The internal workings of the system shell are
detailed so the reader can implement their own replacement shells.
Chapter 14 is basically the associated documentation to the user
shell.
        The next section is a short history of the AmigaDOS
filesystem, and a complete guide around the filesystem and its on-disk
data structures. This knowledge would be handy when using a disk editor
to repair a trashed hard disk or floppy. A history of BCPL and how it
works is mentioned, and a source code example of the MakeDir command
in BCPL is included.

        The dos.library is documented extensively with explanations of
each function. The general format of each function is as follows:

        17.1.142  UnLock()

        Purpose: relinquish a lock on an object

        Prototype: void UnLock(BPTR);
                         -90    D1

        D1 -- BPTR to struct FileLock

        A description of UnLock() follows along with any "see also:"
type references, such as CreateDir(), DupLock(), and so on. Since
there are many dos.library functions here, no attempt will be made to
discuss each one.

Error codes are documented towards the end of the dos.library section.
Ralph explains how and why each code is implemented.

        Chapter 21 deals with Packets and Handlers. This is a complete
reference on how to implement "DOS devices" like CON, AUX,
SER/PAR/PRT, PIPE, and replacement filesystems like CrossDOS and
CD_ROM filesystems. Much like the dos.library section, each packet
action is explained.

        21.2.2.2  ACTION_FREE_LOCK

        Purpose: release a filesystem object

        Implements: AmigaDOS function UnLock()

        dp_Type -- ACTION_FREE_LOCK

        dp_Arg1 -- BPTR to struct FileLock

        dp_Res1 -- LONG (success code; DOS boolean)
        dp_Res2 -- LONG (AmigaDOS error code if dp_Res1 == DOSFALSE)

Discussion follows much like the dos section.

        There is C source code to "ASynCopy" - file copy using
asynchronous packets and C source for "UnMount" to remove an AmigaDOS
handler and free its resources.

        In chapter 22 the format of object modules and executable
programs are discussed along with hunk types, the components of a
hunk, how they work and what they are used for.

        Last but not least, this book has appendices, a glossary and
an exhaustive index. In the appendix, Babel notes that the source
listings in the book are mainly for reference, even though they are
fully functional. The listings have been printed in a format to detect
typos and omissions. A three digit checksum has been appended to each
line so that the integrity of the code can be checked. The source for
the "checksum" program is included.
        Makefiles have been supplied for all programs. All programs
were compiled with SAS/C 5.10b and SAS/C 6.2. All sources were
compiled with the release 2.04 headers and the 2.02 headers included
with SAS/C 5.10b.

CONCLUSION

        The Amiga Guru Book is a "must have" for any serious
programmer. There are many details in this manual that just cannot be
put into any kind of review. There is a lot of everything for every
programmer here. An abundance of basic computer knowledge comes along
with the explanations and examples given. This is a big plus for
novice programmers or someone just looking for a place to start.
        I would have given anything to have had this book available
when I first started peering through the sometimes cryptic Rom Kernel
Manuals. This is the perfect companion to the RKM set especially since
the information is so detailed. It tends to fill in spots in the RKM's
that are hazy or ambiguous.
        Nowhere else will one find so much information on AmigaDOS,
and its filesystem as in this book.


LIKES AND DISLIKES

        I found nothing in The Amiga Guru Book to really dislike. It
is detailed and concise. Explanations are very clear.
        The sheer scope of this book is truly amazing. There isn't
much about Intuition or Graphics, but the Rom Kernel Manuals were
meant for that. When you need to find something about DOS though, this
is the reference to turn to. You will find yourself returning to it
often since it is a very solid source of information.
        One thing I do like is the cross referencing of everything
that needs it.
        Ralph Babel's humor is evidenced on many pages and makes
reading it interesting and enjoyable. At the first of each chapter are
quotes from notable names in the Amiga community, such as Andy Finkel,
Dave Haynie, Michael Sinz, and Leo Schwab. These quotes are humorous
and unusual to find in a book of this type. But then, this is an
exceptional book.

"A disk does not have to be inserted to be examined by DISKED."
        -- The AmigaDOS Manual, 2nd edition


COMPARISON TO OTHER SIMILAR PRODUCTS


        There really is no similar product to compare this book to,
except the AmigaDOS manuals by Bantam, and they are weak in
comparison. The Guru Book supplements the Amiga Rom Kernel Manuals
very well.


CONCLUSIONS


        With 736 pages of excellent information and programming
examples, The Amiga Guru Book is superb. Every serious programmer
would benefit from owning a copy. Information found here is difficult
to find, but Ralph Babel has put it all together rather efficiently.
        Unfortunately, when reviewing this book, I can only touch
lightly on what it has to offer. The Amiga Guru Book is not easily
read in just a few nights, or even a few weeks for that matter.

It is after all, a reference book to read and refer to repeatedly.

        I rate The Amiga Guru Book 5 stars out of 5.

Available from:

NBG USA, Inc.                    Almathera Systems
482 Holly Avenue                 Southerton House
St. Paul, MN 55102               Boundary Business Court
USA                              92-94 Church Road
Voice: +1 (612) 290 9447         Mitcham, Surrey CR4 3TD
Fax:   +1 (612) 290 9449         UK
                                 Voice: +44 181 687 0040
                                 Fax:   +44 181 687 0490
                                 E-Mail: almathera@cix.compulink.co.uk

Hirsch & Wolf OHG                Stefan Ossowskis Schatztruhe
Mittelstrasse 33                 Gesellschaft fuer Software mbH
D-56564 Neuwied                  Veronikastrasse 33
Germany                          D-45131 Essen
Voice: +49 (2631) 8399-0         Germany
Fax:   +49 (2631) 8399-31        Voice: +49 (201) 788778
                                 Fax:   +49 (201) 798447
                                 E-Mail: stefano@tchest.e.eunet.de

Someware
27 rue Gabriel Peri
59186 Anor
France
Voice: +33 27596000
Fax:   +33 27595206
E-Mail: didierj@swad.someware.com


LIST PRICE

        The recommended price is DM 79, in Germany, which would be
about $49.95 (US).


COPYRIGHT NOTICE


        Copyright 1994 Patrick Riley

        You can contact the author of this review at:

        Internet: Pat_A_Riley@cup.portal.com

        Or: Patrick Riley
            1600 Iris St.
            Amarillo, TX
            79107